ALARMLX Documentation, by Joseph K. Horn - 89/06/02

Lexfile by Mastny J. Michael, 1986

************
* FEATURES *
************

ALARMLX gives to the HP-71 the same power that the HP-41CX enjoys: the ability
to set multiple alarms for any time and date, message or control alarms,
interrupting or non-interrupting, and one-shot or repeating alarms.  One new
feature which the HP-41CX does not have: you can specify how many times a
repeating alarm is to activate before clearing itself.

ALARMLX also contains equivalents of the HP-41CX's ALMCAT (alarm catalog),
and CLRALMS (clear all alarms).  New to ALARMLX, however, is the ability to
clear just the one alarm at a given time and date.

************
* KEYWORDS *
************

AE/01 ALARMCAT
AE/02 ALARMOFF
AE/03 DELALARM
AE/04 SETALARM
AE/05 SETSOFT

************
* SETALARM *  date$, time$, command$ [; repeat interval$, executions]
************

This sets an alarm: "On this date, at this time, do this comand".  The repeat
interval is given in standard HP-71 time format; this tells how long to wait
before repeating the alarm.  If the repeat interval is given, you must also
give the number of executions, which tells how many times the alarm should
repeat, after which it clears itself permanently.

The alarms set by SETALARM are called "interrupting alarms" because they can
interrupt a running BASIC or BIN program when they come due.  If this is not
desired, use non-interrupting alarms (see SETSOFT below).  NO alarms EVER
interrupt a function or statement.  If an alarm comes due during the operation
of a time-consuming function (like the MATH ROM's "FNROOT") or statement (like
the JPC ROM's "KA"), then the alarm annunciator comes on (in the upper right
corner of the display), and the alarm waits for the function or statement to
finish before executing its command string.  This allows you to use CONT to
resume BASIC programs after they've been interrupted by an alarm.  Since BIN
programs (like Chris Capener's "RPN") cannot be resumed if interrupted, and do
not behave predictably when interrupted, NEVER USE SETALARM when using BIN
programs.  Use SETSOFT instead.

EXAMPLES:

SETALARM "89/06/02","11:00:00","BEEP @ DISP 'DONUT TIME!' @ BEEP"
   sets an alarm for June 2nd, 1989 at 11am, to say DONUT TIME! and beep twice.

SETALARM DATE$,"13:55:00","BEEP1400,.08";"00:00:01",5
 sets alarm to chirp 5 times, one second apart, at 1:55pm today.

SETALARM "89/06/02","06:30:00","RUN WAKEUP";"24:00:00",1000000
 runs "WAKEUP" (user's program) every day at 6:30am, for a million days

 Note: the number of executions must lie between 0 and 1048575, and
       the repeat interval must lie between 00:00:01 and 99:99:99.
       The date must be in "YY/MM/DD" or "YYYY/MM/DD" format, and
       the time in "HH:MM:SS" format between "00:00:00" and "23:59:59".
       The command string may be any line legal in keyboard BASIC;
       statements not allowed from the keyboard (like DEF) cannot be used.

***********
* SETSOFT *  date$, time$, command$ [; repeat interval$, executions]
***********

The syntax of SETSOFT is exactly the same as SETALARM (see above).  The only
difference is that SETSOFT sets a non-interrupting ("soft") alarm.  When it
comes due (or repeats), it behaves just like a SETALARM alarm, unless there is
a BASIC or BIN program running.  If so, it turns on the alarm annunciator
(in the upper right corner of the display), and waits until the program stops
before executing its command string.

EXAMPLES: see SETALARM above.

************
* ALARMOFF *
************

Clears all pending alarms permanently.

************
* DELALARM *   date$, time$
************

Clears the alarm due at that date and time.  If more than one alarm is due at
that date and time, only one is cleared: the one most recently set.

EXAMPLE:

DELALARM "89/12/25","00:00:00"
 clears the alarm due on midnight of Christmas 1989.

************
* ALARMCAT *
************

Begins the Alarm Catalog.  Like CAT ALL, you must press the down-arrow key to
proceed through the catalog; if you do not have a video interface, you will
also need to scroll the display with the left and right arrow keys.

SETSOFT alarms are indicated by the line "Soft Command".

NOTES:  If an alarm comes due when the HP-71 is turned off, ALARMLX willl turn
        it on automatically.  This allows it to be used as an alarm clock, an
        unattended time-based device controller and data logger, etc.

        All HP-71 buffers are limited to 4K each.  This means that you can
        only set a certain number of alarms. This number will depend on how
        long the command strings are.  If you try to set too many alarms, you
        will see the error message "Too many Alarms", and the alarm will not be
        set.  Use ALARMCAT and DELALARM to weed out some alarms to make room
        for new ones.

        Memory is used as follows: The alarm buffer itself uses three bytes,
        and each alarm uses 22 bytes plus the length of each alarm's command
        string.  Intervals take up no memory.  So, if you average 40-
        character command strings, you can set about 66 alarms.

        If you wish to use a non-interrupting alarm, yet have a program test
        to see if it has come due, you can test flag -60, the alarm annunciator
        flag.

        If two alarms come due at the same moment, the one most recently set is
        the one executed first.

        ALARMLX uses buffer #816 (hex).

******* End of ALARMLX documentation *******